Help Builder, (c) Copyright 1995, by JJ Software A: Beginning Information The install program defaults to \CLARION3 as the install to directory. Two files CFDHB.EXE and CFDHB.INI will be placed in this directory or the directory you choose as the install directory. The rest of the Help Builder files will be placed in a subdirectory under the install directory with the name of \CFDHB. The CFDHB.EXE and the CFDHB.INI must always be together and in your path when using the program. After installation go to a directory with your source code and type CFDHB. *** The configuration file should be completed if you wish to read source code and you also have an existing Help file and Text file that you want read. *** The existing Help files information gets copied into the main data file. All this information would then not need to be entered again to create the new Help file. !! IMPORTANT 1. The CFDHB.EXE and the CFDHB.INI must always be together and in your path when using the program. 2. A subdirectory named $CFDHB$ is created when you start Help Builder. This directory holds the data files for your read source code, help file and text files. This directory is created where you start Help Builder so you would normally run Help Builder from the directory that your application resides or your source code. 3. The CFDHB.INI file has an environment variable, CFDHB , that holds the path you gave on installation. If this directory path changes or if you change the INI file you must make sure that the INI file and the directory match. This directory holds files Help Builder needs to run the custom editor and batch files. A file named MKHBINI.EXE is in the subdirectory \CFDHB. This file will create the CFDHB.INI file with the proper configuration. You need to run this program in the \CFDHB directory for it to create the INI file properly. 4. Maximum file size in the custom editor is 64k. You should use more than one text file for your help project if the text file is going to be larger than this. This way you can use the same Help file but any number of text files. This is documented in the help about text files. B: Help Builder and its purpose: To help you build a Clarion for DOS Help project for your application that uses a help screen list box and lookup sections and topics in a text file. This applies also to the dual list box help screen in Clarion for DOS 3.1. This program is designed to read the source code for Help IDs declared anywhere they can be placed in your source code or application. Other information from the screen or pulldown is also recorded to help assist you while you enter the sections and topics for each Help ID. You do not have to go into the Clarion for DOS IDE Help Editor if you only want your help project to display ascii help text in a help screen list box. All work can be done from one browse after the source code has been recorded. A custom text file editor is used to find each section and/or topic to edit. Super Memo 3 from Bobcat Systems is the editor used. It has been modified for this program. This is not a 'screen formatter', it will not build help screen information. It will create the Sections and Topics(records) in a Clarion Help file and then also copy the section/topic identifier to a Text file. The maximum ascii file size is 64 K for a text file. C: Help File Utility A utility is included inside Help Builder that allows you to copy any Clarion for DOS help record(any Help ID with screen information or not) from one help file to another. D: Important information about Help Builder 1: Editor width setting You need to set the width you want for your text file. This is used for the word wrapping feature in the editor. You generally want the width to be the same width you give the help screen list box. Size or the width of the Section/Topics should be considered when you set the size of the page width for the text file. If the width of the paper is smaller than the length of the Section or Topic then when either of these get written to the text file they will be cut off before the terminating bracket on the right side. 2: Changing Sections and Topics: You should do all your changing of sections or topics from within the browse of the main data file. This is the file that was loaded when all the source code was read. Warning ! Try not to make changes to the text file sections and topics from within the text file with an editor. If you do you should select RELOAD text file from the menu and and let Help Builder reload the text file and link the sections and topics back to the main data file. If you do not do this you are going to spend more time trying to find the sections and topics because they will not be linked. This means the custom editor cannot find the proper section/topic because they are not linked to the main data file and a Help ID. 3: Description line in text file: This is a field in your configuration file and it can be very useful in your text file. This is a string that will get placed below the section/topic in the text file. The section/topic identifier is not seen in the Help screens List box. This string would allow the description of the section/topic to be seen by the end user. Normally topics would be the best place to use these. The reason is topics are seen while viewing the section they are in. A description below each topic allows scrolling through the section seeing each topics heading without pressing the Related Topics button. Important !!! This string is read one line below the identifier. If normal help text information in your existing text file starts there you should turn this feature off. The program will read this line and prime the main data file with incorrect information. 4: Changing Sections: Changes made to the section description from the main data file browse will be changed in the text file when selecting the final build from the menu. The new help file will also receive the changes. This is the proper place to make changes to sections and topics. 5: Unlinked Help & Text: Unlinked Help IDs get copied to the new Help file. They do not get their section/topic copied to the Text file. Only sections and topics from the main data file get copied to the Text file. Unlinked Text file sections and topics only have a browse to display in to show you they are in your text file and do not link to any Help ID in your source code. IMPORTANT !!! E: Help Builder characteristics This is a list of topics that explain certain characteristics about Help Builder. They could be duplicated in the context sensitive help but are here as a helpful way to see some important issues that you need to be aware of while using this program and creating a Clarion for DOS help system. 1: Help Screens associated with a help id: If a Help ID is going to have a screen designed instead of being displayed in a help screen list box leave the help information empty in the main data file browse. The screen will need to be created in the Clarion for DOS IDE help editor or copied into the help file using the Help File Utility that is part of Help Builder. This help screen will be copied over to the new help file created on the final build. Leave any screens in the new help file. They will always be copied over to the new help file if your configuration file is set to copy all unlinked Help ID's. Screens always appear as Unlinked Help IDs in the HB2HLP.DAT file. This file holds all the Help IDs read from the help file set in your system configuration form. The decision was made while developing this program to not link these help id screens to the HB1MAIN.DAT files Help IDs read in your source code. This allows you to easily change your help systems design. ! REMEMBER: Screens and any information are not copied into the main data file. All the information about a screen is copied over to the new help file on the final build. Do not enter any information about this Help ID in the main data file browse. If you do a Help ID will be created in the new help file with the same name as the screen. Unpredictable results will happen with this condition. 2: Size of the margins and Sections/Topics: Size or the width of the Section/Topics should be considered when you set the size of the page width for the text file. If the width of the page is smaller than the length of the Section or Topic then when either of these get written to the text file they will be cut off before the terminating bracket on the right side. This would happen when you save the file while in the editor. 3: When adding a topic to a section: We must choose which Help ID with its section to choose from. This will add the link to the proper section. When we write this information back to the text file we will need to only write this topic under this section. We need to do this because we can have more than one section with the same name. This condition is really not acceptable but it can happen when creating sections for your Help IDs. 4: Changing Sections and Topics: You should do all your changing of sections or topics from within the browse of the main data file. This is the file that was loaded when all the source code was read. Warning ! Try not to make changes to the text file sections and topics from within the text file with an editor. If you do you should select RELOAD text file from the menu and and let Help Builder reload the text file and link the sections and topics back to the main data file. If you do not do this you are going to spend more time trying to find the sections and topics because they will not be linked. This means the custom editor cannot find the proper section/topic because they are not linked to the main data file and a Help ID. 5: Changing Sections: Changes made to the section description from the main data file browse will be changed in the text file when selecting the final build from the menu. The new help file will also receive the changes. This is the proper place to make changes to sections and topics. 6: Unlinked Help Ids: Unlinked Help IDs get copied to the new Help file. They do not get their section/topic copied to the Text file. 7: Duplicate Sections are only allowed for two conditions: When you have the same name Help ID declared more than once the program knows this and keeps all of these sections the same for you. You are always changing just the first numbered Help ID in this sequence. If you make a change all the same named Help IDs get changed. When you have a topic you must have a section to go with it. All topics under a section would of course have the same section. Any other time the program will not allow you to duplicate sections. This is done to prevent one from making a mistake and entering the same section twice. You might not catch this during development of an application. If you ever needed this you would have to copy all the information from under one section and copy it to the other section. 8: Description line in text file: This is a field in your configuration file and it can be very useful in your text file. This is a string that will get placed below the section/topic in the text file. The section/topic identifier is not seen in the Help screens List box. This string would allow the description of the section/topic to be seen by the end user. Normally topics would be the best place to use these. The reason is topics are seen while viewing the section they are in. A description below each topic allows scrolling through the section seeing each topics heading without pressing the Related Topics button. Important !!! This string is read one line below the identifier. If normal help text information in your existing text file starts there you should turn this feature off. The program will read this line and prime the main data file with incorrect information. FILES THAT GET INSTALLED: A:PLACED IN THE INSTALL DIRECTORY CFDHB.EXE HELP BUILDER CFDHB.INI HELP BUILDERS INI FILE B:PLACED IN THE \CFDHB SUBDIRECTORY README TXT THIS FILE HB HLP MAIN HELP FILE HB TXT HELP TEXT FILE HBADL TXT HELP TEXT FILE HBEDT TXT HELP TEXT FILE HBHFU TXT HELP TEXT FILE HLPSCR HLP A DEFAULT HELP SCREEN MKHBINI EXE CREATES THE HELP BUILDER INI FILE MYEDT BAT RUNTIME BATCH FILE MYSHELL BAT RUNTIME BATCH FILE ORDER FRM ORDERFORM PRINTER CTL HELP BUILDER PRINTER CONTROL SMEDTCMD DAT EDITOR FILE SMEDTCMD K01 EDITOR FILE SMEDTCMD K02 EDITOR FILE SMKEYNAM DAT EDITOR FILE SMKEYNAM K01 EDITOR FILE SMKEYNAM K02 EDITOR FILE SMMACRO DAT EDITOR FILE SMMACRO K01 EDITOR FILE SMMACRO K02 EDITOR FILE SMPRTCMD DAT EDITOR FILE SMPRTCMD K01 EDITOR FILE SMPRTCMD K02 EDITOR FILE SMPRTMDL DAT EDITOR FILE SMPRTMDL K01 EDITOR FILE SMPRTMDL K02 EDITOR FILE SMPRTSEQ DAT EDITOR FILE SMPRTSEQ K01 EDITOR FILE SUPPLMNT DCT EDITOR DICTIONARY FILE USENGLSH DCT EDITOR DICTIONARY FILE WORDPERF SMK EDITOR KEY FILE WORDSTAR SMK EDITOR KEY FILE EXTRAKEY SMK EDITOR KEY FILE ****************** IF THE RUNTIME EDITING IS PURCHASED ******************* RUNTIME HELP FILE EDITING: Also RUNTIME help editing of your program is possible. You need to follow guidelines in the RUNTIME.TXT file. The main rule is to compile your application WITHOUT USING RUNTIME LIBRARIES. Using the Clarion Dll XXXCLA.DLL runtime library will not work(at this time). That means you can compile with overlay or protected mode memory models with 'Use Runtime Libraries' NOT checked. When running your EXE you press the F1 key and you are in the text file with the editor at the section or section/topic for the active Help ID. Write if you are interested in this module. The price will be: ___ Run Time Editing latest version .......... @ $19.00 ea. $ ____.__ (Includes a disk with the latest authorized registered version & on-disk documentation.) Disk format 3.5" 1.4M Shipping & handling -- $2.55 in U.S.A., $7.05 outside U.S.A., $4.05 for Canada: $ ____.__ Subtotal: $ ____.__ Florida clients add 6.5% sales tax on Subtotal: $ ____.__ TOTAL (check or money order enclosed): $ ____.__ ****************** IF THE RUNTIME EDITING IS PURCHASED *******************